home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 May: Tool Chest / Developer CD Series May 1996 (Tool Chest) (Apple Computer) (1996).iso / Tool Chest / Development Tools & Languages / Dylan Related / Mindy / Mindy 1.2 - Mac PPC / doc / format.txt < prev    next >
Encoding:
Text File  |  1995-03-15  |  7.1 KB  |  205 lines  |  [TEXT/MMCC]
  1. [NOTE: This file has been generated by a series of translation tools that
  2.  converted an original FrameMaker .mif file to this .txt file.  The
  3.  conversion tools created the table of contents and uppercased all
  4.  identifiers.  The printed representation of all identifiers in this
  5.  interface is lowercase.  The conversion tools also sometimes drops hyphens
  6.  from identifiers, so if you think a name should have a hyphen in it, it
  7.  probably does.  It is not worth the effort to manually fix this .txt file
  8.  to correct these problems.]
  9.  
  10.  
  11.                            GWYDION FORMAT FOR DYLAN
  12.                            ========================
  13.  
  14. Designed by the Gwydion Project
  15.  
  16. Version 1.0 :
  17.  
  18. ------------------------------------------------------------------------------
  19.  
  20. Table of Contents
  21. -----------------
  22.  
  23. 1.  Functions
  24.  
  25. 2.  Control Strings
  26.  
  27. ------------------------------------------------------------------------------
  28.  
  29. This document describes the Format library designed by the Gwydion Project
  30. at Carnegie Mellon University. This library extends the functionality of the
  31. format strings described in Dylan's condition system and provides two new
  32. functions for processing the extended format strings. The Format library is
  33. a small library, but it requires the Print library and some of the Streams
  34. library and from the Gwydion Project.
  35.  
  36. 1.  Functions
  37. -------------
  38. The Format library offers two functions, format and format-to-string.
  39.  
  40. format  [Generic Function]
  41.  
  42.     Arguments
  43.         stream :: <stream>
  44.         control-string :: <string>
  45.         #rest arguments
  46.     Values
  47.         none
  48.     Description
  49.         Performs output to stream according to the directives in
  50.         control-string. Each directive consumes one argument from arguments.
  51.         The control-string contents that are not part of any directive are
  52.         output directly to stream, as if by the Stream library's write
  53.         function.
  54.  
  55. format  [Method]
  56.  
  57.     Arguments
  58.         stream :: <stream>
  59.         control-string :: <byte-string>
  60.         #rest arguments
  61.     Values
  62.         none
  63.     Description
  64.         There is one method for format, and it is specialized to
  65.         <byte-string>s.
  66.  
  67. format-to-string  [Generic Function]
  68.  
  69.     Arguments
  70.         control-string :: <string>
  71.         #rest arguments
  72.     Values
  73.         result :: <string>
  74.     Description
  75.         Calls format to produce output according to control-string and
  76.         returns the output as a string.
  77.  
  78. format-to-string  [Method]
  79.  
  80.     Arguments
  81.         control-string :: <byte-string>
  82.         #rest arguments
  83.     Values
  84.         result :: <byte-string>
  85.     Description
  86.         There is one method for format-to-string. The control-string
  87.         argument must be a <byte-string>. Result is a <bytestring>.
  88.  
  89. print-message  [Generic Function]
  90.  
  91.     Arguments
  92.         object :: <object>
  93.         stream :: <stream>
  94.     Values
  95.         none
  96.     Description
  97.         Prints object to stream. Methods for this function should print
  98.         objects as a message, as opposed to printing objects in any form
  99.         intending to represent Dylan data, literal syntax, and so on. For
  100.         example, printing a condition object with this function presents the
  101.         condition as an error message, but printing the condition object
  102.         with the print function from the Gwydion Print library prints the
  103.         condition in some form such as {Simple-error}.
  104.  
  105.         See the individual methods for the details of how this function
  106.         prints various objects.
  107.  
  108.         This function exists to define the behavior of the %S format
  109.         directive and to allow users the ability to extend the %S directive.
  110.         Users should have little need to call this function directly.
  111.  
  112. print-message  [Method]
  113.  
  114.     Arguments
  115.         condition :: <condition>
  116.         stream :: <stream>
  117.     Values
  118.         none
  119.     Description
  120.         Prints condition as an error message, as described for the Dylan %S
  121.         format directive. In Gwydion Dylan, this method actually calls the
  122.         report-condition function from the Dylan library's Extensions
  123.         module. Users should not specialize the print-message protocol for
  124.         subclasses of <condition>, but they should instead extend the
  125.         print-message protocol to new condition objects by specializing
  126.         methods on report-condition.
  127.  
  128. print-message  [Method]
  129.  
  130.     Arguments
  131.         symbol :: <symbol>
  132.         stream :: <stream>
  133.     Values
  134.         none
  135.     Description
  136.         Prints symbol to stream by converting it to a string with the as
  137.         function and then writing the string with the write function from
  138.         the Streams library.
  139.  
  140. print-message  [Method]
  141.  
  142.     Arguments
  143.         object :: union(<string>, <character>)
  144.         stream :: <stream>
  145.     Values
  146.         none
  147.     Description
  148.         Prints object to stream by calling the write function from the
  149.         Streams library.
  150.  
  151. 2.  Control Strings
  152. -------------------
  153. The Format library's format strings, or control strings, offer the same
  154. directives as Dylan's format strings offer, but this library provides a few
  155. more directives and permits a single argument to all format directives. The
  156. argument is an integer that must appear contiguously between the dispatch
  157. character (%) and the format directive, and it indicates a printing field in
  158. which to justify the output of the directive. A positive integer indicates
  159. that the output should be flushright within the field, and a negative
  160. integer indicates the output should be flushleft within the field. If the
  161. output length is greater than the field's width, then output occurs as if
  162. there were no field specification. The following are examples of valid
  163. format directives:
  164.  
  165.     %S
  166.     %s
  167.     %15D
  168.     %-10=
  169.  
  170. The following describes the directives:
  171.  
  172.     %S
  173.         Prints the next format argument as a message by calling the function
  174.         print-message on the format argument and the stream. This directive
  175.         is the same as Dylan's %S format-string directive except for two
  176.         features: This library's %S directive outputs character objects, and
  177.         users can extend the %S functionality by adding methods to
  178.         print-message.
  179.     %=
  180.         Prints the next format argument by calling the print function from
  181.         the Print library on the format argument and the stream. Users can
  182.         extend the %= functionality by adding methods to the print-object
  183.         function from the Print library.
  184.     %C
  185.         Print the next format argument, which must be a character, according
  186.         to Dylan's %S format-string directive. This library's %C directive
  187.         is the same as this library's %S directive.
  188.     %D
  189.         Prints a decimal representation of the next format argument, which
  190.         must be an integer.
  191.     %B
  192.         Prints a binary representation of the next format argument, which
  193.         must be an integer.
  194.     %O
  195.         Prints an octal representation of the next format argument, which
  196.         must be an integer.
  197.     %X
  198.         Prints a hexadecimal representation of the next format argument,
  199.         which must be an integer.
  200.     %M
  201.         Invokes the next format argument, which must be a function, on the
  202.         stream passed to format.
  203.     %%
  204.         Outputs a single % character.
  205.